---
title: 模型
description: Choose and configure language models for your agents
---

import { Code } from '@astrojs/starlight/components';
import modelCustomProviderExample from '../../../../../../examples/docs/models/customProviders.ts?raw';
import setDefaultOpenAIKeyExample from '../../../../../../examples/docs/config/setDefaultOpenAIKey.ts?raw';
import modelSettingsExample from '../../../../../../examples/docs/models/modelSettings.ts?raw';
import promptIdExample from '../../../../../../examples/basic/prompt-id.ts?raw';
import agentWithModelExample from '../../../../../../examples/docs/models/agentWithModel.ts?raw';
import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw';
import gpt5DefaultModelSettingsExample from '../../../../../../examples/docs/models/gpt5DefaultModelSettings.ts?raw';
import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw';

每个智能体最终都会调用一个 LLM。SDK 通过两个轻量接口对模型进行抽象：

- [`Model`](/openai-agents-js/openai/agents/interfaces/model) —— 知道如何针对特定 API 发起*单次*请求。
- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) —— 将人类可读的模型**名称**（例如 `'gpt‑4o'`）解析为 `Model` 实例。

在日常使用中，你通常只会与模型**名称**交互，偶尔会用到 `ModelSettings`。

<Code
  lang="typescript"
  code={agentWithModelExample}
  title="为每个智能体指定模型"
/>

## 默认模型

当你在初始化 `Agent` 时未指定模型，将使用默认模型。目前的默认模型是 [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1)，它在智能体工作流的可预测性与低延迟之间提供了良好平衡。

如果你想切换到其他模型，如 [`gpt-5`](https://platform.openai.com/docs/models/gpt-5)，有两种方式可以为你的智能体进行配置。

首先，如果你希望对所有未设置自定义模型的智能体始终使用某个特定模型，请在运行智能体前设置环境变量 `OPENAI_DEFAULT_MODEL`。

```bash
export OPENAI_DEFAULT_MODEL=gpt-5
node my-awesome-agent.js
```

其次，你可以为某个 `Runner` 实例设置默认模型。如果你未为某个智能体设置模型，则会使用该 `Runner` 的默认模型。

<Code
  lang="typescript"
  code={runnerWithModelExample}
  title="为 Runner 设置默认模型"
/>

### GPT-5 模型

当你以这种方式使用任一 GPT-5 的推理模型（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 或 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）时，SDK 会默认应用合理的 `modelSettings`。具体来说，它会将 `reasoning.effort` 与 `verbosity` 都设为 `"low"`。若要为默认模型调整推理强度，请传入你自己的 `modelSettings`：

<Code
  lang="typescript"
  code={gpt5DefaultModelSettingsExample}
  title="自定义 GPT-5 默认设置"
/>

为了更低的延迟，使用 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 或 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) 并设置 `reasoning.effort="minimal"`，通常会比默认设置更快返回结果。不过，Responses API 中的一些内置工具（例如文件搜索与图像生成）不支持 `"minimal"` 推理强度，这也是本 Agents SDK 默认使用 `"low"` 的原因。

### 非 GPT-5 模型

如果你传入的是非 GPT-5 的模型名称，且未提供自定义 `modelSettings`，SDK 将回退到与任意模型兼容的通用 `modelSettings`。

---

## OpenAI 提供方

默认的 `ModelProvider` 使用 OpenAI 的 API 来解析名称。它支持两个不同的端点：

| API              | 用途                                             | 调用 `setOpenAIAPI()`               |
| ---------------- | ------------------------------------------------ | ----------------------------------- |
| Chat Completions | 标准聊天与函数调用                               | `setOpenAIAPI('chat_completions')`  |
| Responses        | 新的以流式优先的生成式 API（工具调用、灵活输出） | `setOpenAIAPI('responses')`（默认） |

### 身份验证

<Code
  lang="typescript"
  code={setDefaultOpenAIKeyExample}
  title="设置默认 OpenAI 密钥"
/>

如果你需要自定义网络设置，也可以通过 `setDefaultOpenAIClient(client)` 插入你自己的 `OpenAI` 客户端。

---

## ModelSettings

`ModelSettings` 与 OpenAI 的参数相对应，但与具体提供方无关。

| 字段                | 类型                                       | 说明                                                                      |
| ------------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
| `temperature`       | `number`                                   | 创造性与确定性的权衡。                                                    |
| `topP`              | `number`                                   | 核采样。                                                                  |
| `frequencyPenalty`  | `number`                                   | 惩罚重复 token。                                                          |
| `presencePenalty`   | `number`                                   | 鼓励生成新的 token。                                                      |
| `toolChoice`        | `'auto' \| 'required' \| 'none' \| string` | 参见[强制使用工具](/openai-agents-js/zh/guides/agents#forcing-tool-use)。 |
| `parallelToolCalls` | `boolean`                                  | 在支持的情况下允许并行函数调用。                                          |
| `truncation`        | `'auto' \| 'disabled'`                     | Token 截断策略。                                                          |
| `maxTokens`         | `number`                                   | 响应中的最大 token 数。                                                   |
| `store`             | `boolean`                                  | 持久化响应以便检索 / RAG 工作流。                                         |
| `reasoning.effort`  | `'minimal' \| 'low' \| 'medium' \| 'high'` | gpt-5 等模型的推理强度。                                                  |
| `text.verbosity`    | `'low' \| 'medium' \| 'high'`              | gpt-5 等模型的文本详尽度。                                                |

可在任一层级附加设置：

<Code lang="typescript" code={modelSettingsExample} title="模型设置" />

`Runner` 级别的设置会覆盖任何与其冲突的按智能体设置。

---

## 提示

可以通过 `prompt` 参数为智能体进行配置，指明应使用的服务器存储提示配置来控制智能体行为。目前，此选项仅在你使用 OpenAI 的
[Responses API](https://platform.openai.com/docs/api-reference/responses) 时受支持。

| 字段        | 类型     | 说明                                                                        |
| ----------- | -------- | --------------------------------------------------------------------------- |
| `promptId`  | `string` | 提示的唯一标识符。                                                          |
| `version`   | `string` | 你希望使用的提示版本。                                                      |
| `variables` | `object` | 代入提示中的键/值变量对。取值可以是字符串或文本、图像、文件等内容输入类型。 |

<Code lang="typescript" code={promptIdExample} title="带提示配置的智能体" />

任何其他智能体配置（如 tools 或 instructions）都会覆盖你在存储提示中可能配置的值。

---

## 自定义模型提供方

实现你自己的提供方很简单——实现 `ModelProvider` 和 `Model`，并将该提供方传给 `Runner` 构造函数：

<Code
  lang="typescript"
  code={modelCustomProviderExample}
  title="最简自定义提供方"
/>

---

## 追踪导出器

当使用 OpenAI 提供方时，你可以通过提供 API 密钥来选择启用自动追踪导出：

<Code
  lang="typescript"
  code={setTracingExportApiKeyExample}
  title="追踪导出器"
/>

这会将追踪发送到 [OpenAI 仪表盘](https://platform.openai.com/traces)，你可以在其中检查工作流的完整执行图。

---

## 后续步骤

- 探索[运行智能体](/openai-agents-js/zh/guides/running-agents)。
- 使用[工具](/openai-agents-js/zh/guides/tools)为你的模型赋能。
- 按需添加[护栏](/openai-agents-js/zh/guides/guardrails)或[追踪](/openai-agents-js/zh/guides/tracing)。
